@yarnpkg/fslib

What is @yarnpkg/fslib?

@yarnpkg/fslib is a library that provides a set of utilities for working with the filesystem in a more abstract and high-level way. It is part of the Yarn package manager's ecosystem and is designed to facilitate file system operations, especially in the context of Yarn's plugin architecture.

What are @yarnpkg/fslib's main functionalities?

Path manipulation

This feature allows you to convert native paths to portable paths and vice versa. This is useful for ensuring that paths are consistent across different operating systems.

const { npath } = require('@yarnpkg/fslib');

const nativePath = npath.toPortablePath('/some/native/path');
console.log(nativePath); // Outputs: /some/native/path

File reading and writing

This feature provides asynchronous methods for reading and writing files. It simplifies file operations by providing promise-based APIs.

const { xfs } = require('@yarnpkg/fslib');

(async () => {
  const filePath = '/path/to/file.txt';
  await xfs.writeFilePromise(filePath, 'Hello, world!');
  const content = await xfs.readFilePromise(filePath, 'utf8');
  console.log(content); // Outputs: Hello, world!
})();

Directory operations

This feature allows you to perform directory operations such as creating directories and reading their contents. It supports recursive directory creation.

const { xfs } = require('@yarnpkg/fslib');

(async () => {
  const dirPath = '/path/to/directory';
  await xfs.mkdirPromise(dirPath, { recursive: true });
  const files = await xfs.readdirPromise(dirPath);
  console.log(files); // Outputs: list of files in the directory
})();

Other packages similar to @yarnpkg/fslib

fs-extra

fs-extra is a popular library that extends the native Node.js fs module with additional methods and promises. It provides similar functionalities to @yarnpkg/fslib, such as file and directory operations, but it is more general-purpose and not specifically tied to the Yarn ecosystem.

node-fs

node-fs is another library that extends the native fs module with additional features like recursive directory creation and symbolic link support. It offers similar capabilities to @yarnpkg/fslib but is less focused on path manipulation and more on enhancing the core fs module.

graceful-fs

graceful-fs is a drop-in replacement for the native fs module that improves its reliability, especially under heavy load. While it doesn't offer as many high-level utilities as @yarnpkg/fslib, it ensures more robust file system operations.

README

@yarnpkg/fslib

A TypeScript library abstracting the Node filesystem APIs. We use it for three main reasons:

Type-safe paths

Our library has two path types, NativePath and PortablePath. Most interfaces only accept the later, and instances of the former need to be transformed back and forth using our type-safe utilities before being usable.

Custom filesystems

The FSLib implements various transparent filesystem layers for a variety of purposes. For instance we use it in Yarn in order to abstract away the zip archive manipulation logic, which is implemented in ZipFS and exposed through a Node-like interface (called FakeFS).

All FakeFS implementations can be transparently layered on top of the builtin Node fs module, and that's for instance how we can add support for in-zip package loading without you having to care about the exact package format.

Promisified API

All methods from the FakeFS interface are promisified by default (and suffixed for greater clarity, for instance we offer both readFileSync and readFilePromise).

Changelog

3.1.0

Commands

• The yarn workspaces list and yarn workspaces foreach commands now both support a new --since option that lets you filter the workspace list by changes (only workspaces that changed since the specified commit will be iterated on). This feature is still a little experimental, especially when used with -R,--recursive.
• The yarn workspaces foreach command now handles the fact that a script containing : only becomes global if it exists in exactly one workspace.
• The yarn workspaces foreach command now supports --jobs 1 and --jobs unlimited.
• The yarn init -2 command will now add the packageManager field to your project manifest.

Settings

• The pattern matcher from logFilters will now match any part of the log entry.

Installs

• A new nodeLinker: pnpm mode will let you install packages using the pnpm install strategy, where packages are stored flat and referenced by each others through symlinks. This mode is still a little experimental, so please send our way bugs you might find.
• Yarn won't install anymore packages that don't match the current OS. Should you need to (for example if you check-in your cache), use the supportedArchitectures field to manually enforce the presence of specific architectures.
• The nmMode: hardlinks-global setting will now be automatically downgraded to nmMode: hardlinks-local when global caches and install folders are kept on different devices, thus letting the install continue normally. A warning will still be produced explaining this behaviour.
• The node_modules linker maximizes chances to end-up with only one top-level node_modules in the case of using workspaces
• The nmSelfReferences setting has been added to the nm linker to control whether workspaces are allowed to require themselves - results in creation of self-referencing symlinks. yarn workspaces focus will not create self-referencing symlinks for excluded workspaces anymore.
• Yarn can now install workspaces from remote git repositories that use npm if npm@>=7.x is installed on the system.
• The hoisting algorithm should be faster, improving the install time for recurrent node_modules installs.

Miscellaneous Features

• Workspaces can now be referred to using workspace:^ and workspace:~. When published, those markers will turn into the actual version (just like what used to happen with workspace:*), except that they'll be prefixed with the relevant semver prefix (respectively ^ and ~).
• A new npmAuditRegistry setting will let you define which registry to use when running audits. If unset, we'll fallback to the currently configured publish registry (we'll likely change this behavior in Yarn 4 to rather use the fetch registry).

Bugfixes

• Direct portal dependencies for node_modules installs will now be given priority during hoisting, preventing cases when indirect regular dependencies would block the way for direct portal dependencies.
• The pnpify binary can now be used from inside directories containing spaces.
• The CLI bundles built from sources will now output the commit hash instead of the tree hash, as part of their --version string.
• Nested workspaces are properly hoisted by node-modules linker.
• Self-referencing symlinks won't be created for anonymous workspaces when using the node-modules linker, since they cannot be used from the code anyway.
• The cache is now fully atomic when moving files across devices, and is more efficient in general.
• The PnP patch will now properly pick up changes to the fs module, allowing users to patch it.
• When using PnP, require.resolve('pnpapi') will be handled correctly even when using exports.
• The install state will no longer be invalidated after running commands that modify the lockfile; this should bring a significant performance improvement when running commands such as yarn run immediately after adding or removing dependencies inside large monorepos.
• Optional peer dependencies now imply an optional peer dependency on the corresponding @types version. This matches the behaviour for peer dependencies.

Compatibility

• Yarn will now generate an experimental ESM loader when it detects you may need it. This can be disabled (or enabled) using pnpEnableEsmLoader.
• The PnP compatibility patch for resolve will no longer resolve missing modules to a file with the same name that would happen to be located next to the issuer.
• Fixes the SDK to account for a breaking change in VSCode >=1.61.